home *** CD-ROM | disk | FTP | other *** search
/ 17 Bit Software 6: Level 6 / 17 Bit - Level 6 (1998)(Epic Marketing)[!].iso / quartz / q1174.dms / q1174.adf / runlame_v1.28 / docs / RunLameInfiltrator_V1.6.doc < prev    next >
Text File  |  1993-08-25  |  21KB  |  462 lines
  1. ____________________________________________________________________________
  2.  
  3. $VER: RunLameInfiltrator V 1.6 documentation (© by Bilbo the first of Hypenosis on 25.08.93)
  4. ____________________________________________________________________________
  5.  
  6.  
  7.                              RunLameInfiltrator
  8.                              ==================
  9.  
  10.                          (FileLinker/FileUnlinker)
  11.  
  12.                    Copyright 1992-1993 by Bilbo the first
  13.  
  14.  
  15. Accept this or delete the complete package now:
  16. ----------------------------------------------
  17.  
  18. This  software  is NOT in the Public Domain, NOT Freeware and NOT Shareware.
  19. There  are  NO  warranties, either expressed or implied, with respect to the
  20. software,  its  quality,  performance,  merchantability,  or fitness for any
  21. particular  purpose.   This software is provided "as is" and the entire risk
  22. as  to  its  quality  and  performance is with the user.  The author of this
  23. software  shall  NOT  be  liable for errors contained in the software or the
  24. software's  documentation, or for incidental or consequential damages of any
  25. kind  in connection with the performance, use or posession of this software.
  26. The  use  of  undocumented  features/commands  is  not permitted except with
  27. permission  from  the  author,  and  the author is in NO way responsible for
  28. consequences thereof.  Anyone may use it for private purposes, and it may be
  29. given  away  for  free,  as  long  as  it  is NOT part of any deal involving
  30. purchases;  and  fees for copying and/or distribution, and/or fees for disks
  31. exceeding   the   actual  market  price  for  an  empty  disk  of  the  same
  32. brand/quality  is  to  be  considered  as  commercial  exploitation  of this
  33. software,  and  an  infringement  of  the Copyrights (©) of the author.  The
  34. right to use this software and/or its documentation for private purposes may
  35. or  may  NOT  be  restricted  by  additional  copyrights and/or registration
  36. conditions.   If  given away under above (or below) conditions, the receiver
  37. in  NO  way  receives  the  ownership of the program itself, but may only be
  38. licenced  to  use  it if above and below conditions are met.  If these rules
  39. infringes   the   local   law  and/or  rights  of  any  area,  political  or
  40. geographical,  this  software  is NOT to be used and/or distributed in these
  41. areas.
  42.  
  43. For  further license and terms for software originating from Bilbo the first
  44. consult the file Copyright.notice which came with this package.
  45.  
  46. This package is PrayWare, please read the file PrawWare.license.
  47.  
  48.  
  49. Table of contents:
  50. -----------------
  51.  
  52.                             The aim of the game
  53.                                   Features
  54.                                 The bad news
  55.                        How to use RunLameInfiltrator
  56.                      How to use FileLinker/FileUnlinker
  57.                        Configuring RunLameInfiltrator
  58.                        Problems - solutions - corner
  59.                                  Known bugs
  60.                                 Future plans
  61.                                   History
  62.                              Thanks, greetings
  63.  
  64.  
  65. The aim of the game:
  66. -------------------
  67.  
  68. Do  you  run  your  system  using  another  screenmode than PAL or NTSC, for
  69. example  EURO72 or an AGA specific screenmode?  Have you ever tried to start
  70. a  game or demo from within this screenmode?  Have you ever been angry about
  71. those  programmers  who  do  not stick to the guidelines of programming thus
  72. producing  programs  which are not aware of the screenmode they were started
  73. out of?
  74.  
  75. Do  you  have an Amiga with 68010, 68020, 68030 or 68040 processor?  Did you
  76. ever curse those socalled coders whose programs crash your computer when you
  77. didn't  disable  the  processor's  caches and forgot to move the vector base
  78. register back to $0.l?
  79.  
  80. Lame programming is the disease, RunLameInfiltrator is the cure!
  81.  
  82. NEVER  start  RunLameInfiltrator  as stand-alone-program, it definitely WILL
  83. crash  your system.  RunLameInfiltrator MUST be linked to another program to
  84. work correctly.  This process is called `infiltration' in the following, and
  85. the  resulting  file  of  linking  RunLameInfiltrator to a program is called
  86. `infiltrated program'.
  87.  
  88. RunLameInfiltrator  is  a  Kick1.3+ tool, it may work under Kick1.0/1.1/1.2,
  89. but  I  cannot  give  any  warranty  for  this.   RunLameInfiltrator is 100%
  90. pc-relative  and  reentrant  Assembler  code,  so  you  can  link it to pure
  91. programs  and they will stay pure after linking.
  92.  
  93. Just after having degraded the display and the CPU RunLameInfiltrator starts
  94. the  program  it has been linked to.  When the program it has been linked to
  95. has  been  finished  the  display  and  CPU state is restored to the same as
  96. before starting the infiltrated program.
  97.  
  98. Summarizing  we  can  say  RunLameInfiltrator  is  a  multitasking  friendly
  99. temporary  system  degrader which, linked permanently to files, may let some
  100. bad  behaving  programs run in your system's environment (but can't give any
  101. guarantee).    If   some   of   those   `lame'  programs  don't  run  though
  102. RunLameInfiltrator has been used, they are on a higher lameness-level, which
  103. can't  be  fixed  by  RunLameInfiltrator  (this  is  definitely not a bug of
  104. RunLameInfiltrator).
  105.  
  106. I do write demos myself and you can believe, I DO KNOW how to write a proper
  107. startup code.  Consider RunLameInfiltrator beeing a startup code.
  108.  
  109.  
  110. Features:
  111. --------
  112.  
  113. The {}'s inform you about the needed system configuration for a feature.
  114.  
  115.  ·Disabling of all processor caches, burst and copyback modes.
  116.   {68020, 68030[EC], 68040[EC]}
  117.  
  118.  ·Moving vector base register (VBR) to location $0.
  119.   {68010, 68020, 68030[EC], 68040[EC]}
  120.  
  121.  ·Degrading display's screenmode to simulate old chipset (OCS).
  122.   {ECS, AGA}
  123.  
  124.  ·Degrading sprite resolution to simulate old chipset.
  125.   {AGA}
  126.  
  127.  ·Turning off sprites in a system friendly manner.
  128.   {OCS, ECS, AGA}
  129.  
  130.  ·Permanent fix for lame programs.  Fix can be removed.
  131.  
  132.  ·Infiltration of pure programs preserves the reentry ability.
  133.  
  134.  ·Infiltration of pc-relative programs preserves the location relativity.
  135.  
  136.  ·Works under Kickstarts 1.3, 1.4, 2.04, 3.0 and 3.1.
  137.  
  138.  ·Due  to  100% system conform and system friendly algorithms, future system
  139.   compatibility  is  as  high  as  possible.   Furthermore  the multitasking
  140.   environment  is not hurt or damaged by the code.  All degrading is done as
  141.   smart as possible, and the code did never crash during beta testing.
  142.  
  143.  ·verified,  tested  and safe (100% assembler) code resulted in a very short
  144.   binary (so the infiltrated programs only become a little longer).
  145.  
  146. Sounds great?  YAH - Yet another hype?  Hypenosis - Better believe the hype!
  147. But keep on reading, here comes...
  148.  
  149.  
  150. The bad news:
  151. ------------
  152.  
  153.  ·The   infiltrated   programs'   code   is  changed  permanently  (but  not
  154.   irreversible). If you don't like this, use RunLame.
  155.  
  156.  ·No GUI for FileLinker and FileUnlinker.
  157.  
  158.  ·Dangerous FileUnlinker tool (if you don't know what you are doing).
  159.  
  160.  ·The  updating  of  infiltrated programs is slightly uncomfortable (unlink,
  161.   and link again).
  162.  
  163.  ·Though  the  code  worked  very  well during the beta testing phase, there
  164.   might be nasty bugs.
  165.  
  166.  ·RunLameInfiltrator  can't be used to fix non-DOS trackloading demos, for I
  167.   don't  want  to  support this kind of loaders.  I usally like to keep good
  168.   demos  on my harddisk, which is not directly possible with `trackmos'.  So
  169.   I don't keep lame coded `trackmos'.
  170.  
  171.  ·The documentation often might use improper terms.  Please excuse this, for
  172.   I  am  not  a  native  english  speaker.   If  you  want  to  improve  the
  173.   documentation, please contact me.
  174.  
  175.  
  176. How to use RunLameInfiltrator:
  177. -----------------------------
  178.  
  179. In   comparison   to   RunLame   which   is   included   in   this  package,
  180. RunLameInfiltrator  performs  the  following  actions  (which  are RunLame's
  181. default options):
  182.  
  183.  S    = SCREEN          : degrade display
  184.  V    = VISIBLE         : the current display stays visible
  185.  NC   = NOCACHE         : disable instruction & data cache
  186.  NIC  = NOINSTCACHE     : disable instruction cache
  187.  NDC  = NODATACACHE     : disable data cache
  188.  NB   = NOBURST         : disable instruction & data burst mode
  189.  NIB  = NOINSTBURST     : disable instruction burst mode
  190.  NDB  = NODATABURST     : disable data burst mode
  191.  NCB  = NOCOPYBACK      : disable copyback mode
  192.  NEC  = NOEXTERNALCACHE : disable external caches
  193.  NVBR = VBRTO0          : move VBR to $0.L
  194.  CL   = COMMANDLINE cmd : cmd is executed, where cmd is the program
  195.                           RunLameInfiltrator has been linked to
  196.  
  197. The above explained options are active during the execution of `cmd' and the
  198. changed settings of your system are reset to the state active before.  So if
  199. you  know that for example the demo called `ObsoleteFX' will not run on your
  200. normal  system  configuration, infiltrate RunLameInfiltrator to `ObsoleteFX'
  201. and  try  if  it will work.  To link RunLameInfiltrator to `ObsoleteFX', you
  202. can use the following procedure:
  203.  
  204.  FileLinker RunLameInfiltrator name_of_lame_program name_of_output_program
  205.  
  206.  (name_of_output_program is called `the infiltrated program')
  207.  
  208. In this special case use:
  209.  
  210.  FileLinker RunLameInfiltrator ObsoleteFX ObsoleteFX.rli
  211.  
  212. Now  try  if  the  infiltrated  program  works  on  your  system.   When the
  213. programmer(s)  of the un-infiltrated program were too lame it will of course
  214. not  work  :-).   Assuming that ObsoleteFX.rli now works on your system, the
  215. following will happen when ObsoleteFX.rli is started:
  216.  
  217.  assumed system settings before starting ObsoleteFX.rli:
  218.   data cache active        | instruction cache active
  219.   data burst mode active   | instruction burst mode inactive
  220.   external caches inactive | copyback mode active
  221.   VBR in Fast RAM at position p
  222.  
  223.  system settings during execution of ObsoleteFX:
  224.   data cache inactive      | instruction cache inactive
  225.   data burst mode inactive | instruction burst mode inactive
  226.   external caches inactive | copyback mode inactive
  227.   VBR at $0.l
  228.   screenmode changed to PAL,
  229.   sprite resolution changed to lores and sprites turned off
  230.  
  231.  system settings after execution of ObsoleteFX.rli:
  232.   data cache active        | instruction cache active
  233.   data burst mode active   | instruction burst mode inactive
  234.   external caches inactive | copyback mode active
  235.   VBR in Fast RAM at position p
  236.  
  237.  
  238. How to use FileLinker/FileUnlinker:
  239. ----------------------------------
  240.  
  241. At   this   point   I   give   a   short   introduction   to   the  programs
  242. FileLinker/FileUnlinker,   which   I   have   written   a   long  time  ago.
  243. FileLinker/FileUnlinker  is  not  pc-relative,  nor  is it reentrant, so you
  244. can't  make  it resident.  It can't be started from the Workbench because it
  245. doesn't  include  the Workbench startup code.  FileLinker/FileUnlinker works
  246. on  Kick  1.3+, it may work on earlier Kickstart versions, but I cannot give
  247. any  warranty for this.  Both programs may contain bugs and do not represent
  248. my current programming skills (in fact when I read the source lately it gave
  249. me  nightmares).   But  because in all the time I was using both programs no
  250. bugs  have  been  found,  I  just  release both programs unchanged with this
  251. package.   An  easier to use and similar tool I have written when I finished
  252. FileLinker/FileUnlinker.   This  advanced tool is called FileChainer and has
  253. been  released  to the public, so when you want to link normal programs, get
  254. FileChainer  for  this purpose.  In the case of RunLameInfiltrator it is not
  255. possible  to use FileChainer, so we have to use the both older and much more
  256. uglier  programs.   Of  course  you  can use any other known program that is
  257. doing  the  same, but, I don't know of any other released program that could
  258. have been used instead.
  259.  
  260. What  is  FileLinker doing exactly?  FileLinker is able to insert a ONE HUNK
  261. executable file as first hunk into the hunk collection of another executable
  262. file.  The inserted hunk will be started on execution of the resulting file.
  263. This  first  hunk  must  execute the other hunks itself, if this is desired.
  264. You  see,  that  abilites  of  FileLinker are slightly restricted, but it is
  265. exactly what is needed to infiltrate RunLameInfiltrator into a program.
  266.  
  267. To infiltrate RunLameInfiltrator to a program use:
  268.  
  269.  FileLinker RunLameInfiltrator program_name new_program_name
  270.  
  271. FileUnlinker  irreversibly  removes the first hunk of an executable file, so
  272. RunLameInfiltrator  can  be  removed from an infiltrated program.  ATTENTION
  273. FileUnlinker  doesn't  check if the first hunk of the programm that shall be
  274. processed  really  is  RunLameInfiltrator,  so  use  of  FileUnlinker  on an
  275. un-infiltrated   program   results   in   data  loss  and  the  programm  is
  276. irretrievably destroyed.  Be careful with FileUnlinker in your own interest.
  277. You  do  best  if  you check with the Version CLI command of C= if a program
  278. really is infiltrated, before you unlink any hunks of it.
  279.  
  280. To remove RunLameInfiltrator from an infiltrated program use:
  281.  
  282.  FileUnlinker infiltrated_program_name removed_program_name
  283.  
  284.  
  285. Example:
  286.  
  287.  FileLinker RunLameInfiltrator FooBar FooBar.rli
  288.  
  289.  FileUnlinker FooBar.rli FooBar2
  290.  
  291. FooBar2 should be exactly the same as FooBar now.
  292.  
  293.  
  294. Configuring RunLameInfiltrator:
  295. ------------------------------
  296.  
  297. You  can't  take  influence on what RunLameInfiltrator itself is doing.  But
  298. this  chapter  describes how to integrate RunLameInfiltrator into well known
  299. utility environments.
  300.  
  301.  Directory Opus:
  302.  
  303. Enter  the  configuration  module  and the Button section.  Press one of the
  304. still  unused buttons.  Enter `Infiltrate' for |Name| string gadget.  Make a
  305. |New     entry|    which    is    |AmigaDOS|.     Enter    `[path]FileLinker
  306. [path]RunLameInfiltrator  {f}' in the entry string gadget (replace [path] by
  307. the  path were the appropriate file is located).  Enter |Stack size| `4000',
  308. |Priority|  `0',  |Close delay| `-1'.  Uncheck all entries in the |Flags...|
  309. listview  gadget.   Check |Output window| and |Do all files| in the listview
  310. gadget.  Click |Okay|.
  311. Click  on  another  free  button.   Enter `Unlink' for |Name| string gadget.
  312. Make  a  |New entry| which is |AmigaDOS|.  Enter `[path]FileUnlinker {f}' in
  313. the  entry  string  gadget  (replace [path] by the path were the appropriate
  314. file  is located).  Enter |Stack size| `4000', |Priority| `0', |Close delay|
  315. `-1'.  Uncheck all entries in the |Flags...| listview gadget.  Check |Output
  316. window| and |Do all files| in the listview gadget.  Click |Okay|.
  317.  
  318. Save  your  new  configuration.   Now  you  should have 2 new buttons in the
  319. button  bar.   The  `Infiltrate'  button  links  RunLameInfiltrator  to  all
  320. selected  files.   Make  sure  the files are not write and delete protected.
  321. The  `Unlink' button is somewhat DANGEROUS.  It will strip the first hunk of
  322. each  selected  file.   Make sure the files you want to dehunk are not write
  323. and  delete  protected.  THE HUNK STRIPPED OFF THE FILES IS NOT RECOVERABLE,
  324. SO THINK TWICE BEFORE YOU PRESS THIS BUTTON!!
  325.  
  326.  
  327. Problems - solutions - corner:
  328. ----------------------------
  329.  
  330.  ·If you got this error message:
  331.  
  332.                         Screenmode degrading failed!
  333.                  Forbid all promotion utilities to promote:
  334.              "RunLameInfiltrator (© by Bilbo 1st of Hypenosis)"
  335.                Display of this lame program might be trashed!
  336.  
  337.   Then you have probably installed one of the screenmode promotion utilities
  338.   (fi.   The Promotor, NewMode, ForceMonitor, PKludge).  This promotion tool
  339.   will  then  promote  the compatibility screen too, what is a really stupid
  340.   idea.  You should prevent the promotion utility from promoting all screens
  341.   with the title "RunLameInfiltrator (© by Bilbo 1st of Hypenosis)".
  342.  
  343.  ·The  sprite  DMA  shows weird patterns, though you infiltrated the program
  344.   (which  should  turn  off  the sprites, too).  If this happens, one of the
  345.   currently  open  windows  became  active.  All windows have an own pointer
  346.   image,  which becomes active on window activation.  You may have installed
  347.   an AutoPointer/SunMouse utility which activated a window after the sprites
  348.   have  already  been  turned  off.   Avoid this by disabling the apropriate
  349.   application (the window-activating one).  Another possibility is, that the
  350.   infiltrated program opened a window which became active.  You can't easily
  351.   work around the latter problem.
  352.  
  353.  ·The  program  you want to infiltrate is self-detaching and the settings of
  354.   RunLameInfiltrator  are  only valid until the program has detached itself.
  355.   If  the  program has an option to turn off detaching, then use this option
  356.   at  starting  the  program  to prevent detach.  Otherwise, bad luck.  Some
  357.   self-detaching programs even refuse to work after having been infiltrated.
  358.   Other  programs work totally okay after beeing infiltrated.  The behaviour
  359.   depends on the detaching mechanism used by the program.
  360.  
  361.  ·You  have  Enforcer running and your system always hangs when you start an
  362.   infiltrated  Program.   See the Knows Bugs section for an explanantion for
  363.   this phenomenon.  Quit Enforcer before you start an infiltrated program.
  364.  
  365.  
  366. Known bugs:
  367. ----------
  368.  
  369.  ·If  Enforcer is running while RunLameInfiltrator is trying to move the VBR
  370.   to  $0.l,  the  machine  hangs.  Of course this should not happen, I guess
  371.   this  happens  because  some  system  configurations redirect the Enforcer
  372.   output  to  a  window, and when RunLameInfiltrator copies the $0-$400 page
  373.   this  causes  a  whole  bunch of Enforcer hits.  I guess this is a bit too
  374.   much  for  the  Enforcer  window,  but I am not sure about this.  Normally
  375.   there  should  be  reported  several  accesses  to  the addresses $0-$400,
  376.   because  RunLameInfiltrator  MUST save vectors that it is going to change,
  377.   in  order  to  restore  them when leaving (should cause some more Enforcer
  378.   hits).   I  can't work around these Enforcer hits, RunLameInfiltrator MUST
  379.   access these vectors on low level, sorry if this is annoying you.
  380.  
  381.  
  382. Future plans:
  383. ------------
  384.  
  385.  ·Emulation  of  fake  fast  RAM  at  $C00000  on  systems  which have a MMU
  386.   installed.   For this purpose I rely on information about MMU programming,
  387.   which  is  not  yet  available  to  me.   If  you want to help me, send me
  388.   information.
  389.  
  390.  ·NoFastMem, 1mb/.5mb chip mem memory reduction features.
  391.  
  392.  ·I  still  need a native english speaker to correct my lousy english in the
  393.   documentations for RunLameInfiltrator.
  394.  
  395.  ·Do  you  have  any  suggestions  (to  improve  RunLameInfiltrator  or  the
  396.   documentation)?
  397.  
  398.  
  399. History:
  400. -------
  401.  
  402. Refer to the file `RunLameInfiltrator.history' which is distributed together
  403. with  the  RunLameInfiltrator  package.  I thought that history became a bit
  404. massive and most `Joe Average' users won't be interested in it anyway (those
  405. now  might  delete  it  if  they don't need it, but if they wanna distribute
  406. RunLameInfiltrator      to      others,     they     have     to     include
  407. RunLameInfiltrator.history).
  408.  
  409.  
  410. Thanks, greetings:
  411. -----------------
  412.  
  413.  ·Thanks, Jesus Christ for being the god who cares about us all.
  414.  
  415.  ·Thanks  and love to my girlfriend for being such a patient person, may the
  416.   lord bless thee and protect thee.
  417.  
  418.  ·Greets to Zaphod Beeblebrox of Hypenosis (letz do the hype :-).
  419.  
  420.  ·HOARS to ALFred, tète de tomate, greets to Zenith members, too.
  421.  
  422.  ·U4ia,  may  the Lord show you, that he'll never forget about you.  This is
  423.   no hype, you got the vibe, man.
  424.  
  425.  ·Thanx to Delirium for their help.  Without you it would have taken me much
  426.   more longer to implement my first GUI.
  427.  
  428.  ·Thanx  and greets to the brave beta testers (did I forget someone?):  Zap,
  429.   ALFred,  Savage,  Dense,  Sphinx,  Milano, Slammer, Kryss, Andemar, Mnemo,
  430.   Skull,  Ikke,  Gio,  SteveVai,  Starfox,  Gimli, KicStart, Tirreg, Martin.
  431.   (list in no specific order).
  432.  
  433.  ·Greets  to  all the nice pals on irc (Zop, Gucky, Outland, Gateway, Janne,
  434.   Juggi,  Advance,  Goldrnr,  Trooper1,  Shocker, Mag, VAG, duggy, and all I
  435.   know but forgot now (list in no specific order).
  436.  
  437.  ·I  can't  resist:   Comrade,  if you really think you HAVE TO write a text
  438.   about  proper programming, then don't forget to tell the people about VBR.
  439.   BTW,  the  stock  LoadView(NULL)  is not working on A4000, so forget about
  440.   this  (and  it's  not  working  for 1.3!).  And those double CEND are pure
  441.   stupidity,  when  C=  doesn't  say you need two of them for compatibility,
  442.   then  you  definitely  DON'T need two (even your startup code doesn't need
  443.   that).
  444.  
  445.  ·Jolyon  Ralph,  you  seem not to be interested in sharing information with
  446.   me.   Well, I heard KillAGA is a bit useless to the most of the AGA users,
  447.   so  I  might  become  less interested in KillAGA.  It's now your turn, you
  448.   should have my email address.
  449.  
  450.  ·Last  but  not  least,  I  send  encouragement to all those who made these
  451.   despicable  lame  programs,  thus forcing me to spend lots of time writing
  452.   RunLameInfiltrator.   Try  to  do  a  better job about compatibility, next
  453.   time.   Using  RunLameInfiltrator  to  make work your own written programs
  454.   should  be  a shame for you!  One time diskmags will contain compatibility
  455.   ranking lists, I hope.
  456.  
  457.  
  458. For  bugreports,  ideas,  suggestions, improvements, questions and all other
  459. concerning  RunLameInfiltrator meet me on IRC on channel #amiga, #amiga!  or
  460. #amigager.
  461.  
  462.